GAMEMAKER SCRIPTING
document updated 07/17/08

Scripting Language Reference

ABS variable
Returns the absolute (positive) value of variable. For example if X = -5, ABS X will make X = 5

ALERT your message here
Displays a simple alert window with an OK button (no icon, no beep) with the message that you type after ALERT. You can put the value of a variable in an alert by using $variable$. See CAUTIONALERT and NOTEALERT for other alert windows.
Example:
ALERT You have $gold$ gold.

ASC var$
Returns the ASCII value of the first character in var$.

BEEP
Plays the alert sound set in the Sound section of the System Preferences.

BEGIN APPLESCRIPT
  -- write AppleScript code here
END APPLESCRIPT = var$
You can use AppleScript by writing valid AppleScript code in the lines between BEGIN APPLESCRIPT and END APPLESCRIPT. If you use the optional var$ parameter after END APPLESCRIPT, it will put the result, if any, into the variable var$. You can pass variables to AppleScript by using BEGIN APPLESCRIPT var1 var2 etc. AppleScript doesn't accept the $ symbol attached to it's variables, so any GameMaker string variables passed to AppleScript will be converted to the variable name without the $ symbol for use in AppleScript commands. 

CAUTIONALERT your message here
Displays an alert window with a triangle caution icon and an OK button with the message that you place after CAUTIONALERT. You can put the value of a variable in an alert by using $variable$. See ALERT and NOTEALERT for other alert windows.

var1$ = CHR$ var2
Sets var1$ to a string containing the ASCII value of var2.

CLEAR TEXT | PICT
Erases either the picture or text on the card. CLEAR used with no parameter will clear both the picture and text. See REFRESH for restoring the default picture and text.

CONTAINS
Use this to check if a string contains another string. Example:
a$ = "This is a test."
IF a$ CONTAINS "test" THEN ALERT Darn. I wish it was the real thing.

DELAY lengthofdelay
Using DELAY without any parameter will delay until any currently playing sound (if any) is completed. If you put a number after DELAY from 1 to 1000 it will delay for that amount of time (100 = 1 second).

DOMENU ABOUT | NEW | OPEN | SAVE | QUIT
The DOMENU command is used with any one of the 5 menu choices (ABOUT, NEW, OPEN, SAVE, or QUIT) to execute either the "About" menu item in the "Apple" menu or one of the menu items in the "File" menu. The NEW, OPEN, and SAVE commands work even if you selected the "Use minimal menus" option in the "Game Options".
Example:
DOMENU OPEN

END
Ends the game.

EXIT
Exits a script.

EXIT REPEAT
Exits a REPEAT loop.

bool = FILEEXISTS nameOfFile
Returns 1 if the file exists in the same folder as your game. Returns 0 if the file does not exist. You can check for a file in a folder by using nameOfFolder:nameOfFile.

FILEIO CLOSE filenumber
Closes a file that was previously opened with either FILEIO INPUT or FILEIO OUTPUT. Always close a file after you're done reading or writing to it.

FILEIO INPUT filenumber filename$
Opens a file for input so you can read from it with FILEIO READ.

FILEIO OUTPUT filenumber filename$
Opens a file for output so you can write to it with FILEIO WRITE.

FILEIO READ filenumber var$
Reads var$ from the file numbered filenumber. The file must have been opened with FILEIO INPUT and must use the same filenumber.

FILEIO WRITE filenumber var$
Writes var$ to the file numbered filenumber. The file must have been opened with FILEIO OUTPUT and must use the same filenumber. To write variables, use $var$$ for string variables and $var$ for integers.

GETAREA clickAreaNumber x1 y1 x2 y2
Puts the coordinates of the click area specified by clickAreaNumber into the variables x1, y1, x2, and y2.

GETURL url
Accesses a web page if the user's computer can connect to the internet.

GOTOCARD cardnumber
Opens card numbered <cardnumber>. The <cardnumber> must be either a number or variable name. It can't be a card name since card names will be treated as a variable name.

HIDEAREA clickAreaNumber
Hides or turns off the click area numbered <clickAreaNumber>. See SHOWAREA to show a click area.

HIDEBUTTON buttonid
Hides button number <buttonid>. Using HIDEBUTTON alone without <buttonid> hides all buttons on the card. Use SHOWBUTTON to show a button that's been hidden.

HIDECOUNTER
Hides the counter. Use SHOWCOUNTER to show the counter.

HIDESTATUSBAR
Hides the status bar. Use SHOWSTATUSBAR to show the bar.

IF trueExpression THEN dosomething
If the statement after the IF is true, then the code after THEN will be executed. <dosomething> can be any other command except REM.
Examples:
IF X = 10 THEN SOUND Wild Eep
IF key <> 1 THEN ALERT You don't have the key.

IF trueExpression THEN
  ' do commands here
ELSE
  ' do commands here
END IF
This is a block IF command. If the satement after the IF is true, then all of the lines lines between IF and ELSE are executed. If the satement after the IF is false, then all of the lines between ELSE and END IF are executed. ELSE is optional and only needs to be used if you want statements to be executed when the IF line is false. Block IF structures can be nested up to 20 levels deep. See also: SELECT CASE.
Example:
IF X = 100 THEN
  SOUND You Win
  GOTOCARD 99
ELSE
  SOUND You Lose
  GOTOCARD 100
END IF

IMAGEFILE horz vert Filename
Displays a graphics file in the graphics area. The file must be in the same folder as your game unless you use a partial pathname to access a folder within the game's folder (foldername:filename). IMAGEFILE supports any graphics format that QuickTime can support.

INVENTORY ADD item$
Adds item$ to the list of inventory items. There is a maximum of 15 items that can be in the inventory at once.

INVENTORY DELETE item$
Removes item$ from the list of inventory items. If you leave out the item$ parameter, all items will be deleted.

INVENTORY SELECT item$
Lets you select an item from the inventory list. The item name will be placed into the built in variable named inventory$.

INVENTORY WINDOW
Displays the list of inventory items. The item currently selected, if any, will be highlighted. The player can select any item by clicking on the item name in the list. The selected item name is placed into the built in variable named inventory$.

bool = INVENTORY item$
Returns 1 if the item named item$ is in the inventory. Returns 0 if it is not.

KEYDOWN OFF
Turns off KEYDOWN commands. See ON KEYDOWN for inforamtion on using the KEYDOWN command.

var1$ = LEFT$ var2$ x
Sets var1$ to the left x amount of characters in var2$. See also: RIGHT$, MID$, and WORD$.
Example: (This makes b$ = "My name is ")
a$ = "My name is Al" 
b$ = LEFT$ a$ 11

LOOP MOVIE x
Loops a currently playing QuickTime movie, MIDI, or wav file x amount of times or until either another movie is played or a STOP MOVIE command is executed. You can leave out the x if you want the movie to loop an infinate number of times. This command should normally be placed on the line after a MOVIE command.

LOOP SOUND x
Loops the currently playing sound (or the last sound to be played) x amount of times or until either another sound is played or a STOP SOUND command is executed. You can leave out the x if you want the sound to loop an infinate number of times. This command should normally be placed on the line after a SOUND command.

variable = MAX var1 var2 var3
Puts the largest of var1, var2, etc in variable. MAX accepts up to 10 parameters.

var1$ = MID$ var2$ start [length]
Sets var1$ to the characters in var2$ starting at start. If the optional length parameter is used, var1$ will contain that many characters of var2$ unless the end of the string is reached first. See also: RIGHT$, LEFT$, and WORD$.
Example: (This makes b$ = "name")
a$ = "My name is Al"
b$ = MID$ a$ 4 4

variable = MIN var1 var2 var3
Puts the smallest of var1, var2, etc in variable. MIN accepts up to 10 parameters.

MOUSE OFF
Turns off MOUSEDOWN and MOUSEUP commands. See ON MOUSEDOWN and ON MOUSEUP for information on using those commands.

MOVEAREA clickareanumber horz vert
Move click area number <clickareanumber> on the current card <horz> pixels across and <vert> pixels up or down. See also: SETAREA.

MOVIE horz vert nameofmovie
Plays a QuickTime movie file named <nameofmovie> at location <horz>, <vert> in the graphics area of the current card. Movies will only play if the QuickTime extension is installed and the movie file is in the same folder as your game unless you use a pathname to access a folder within the game's folder (foldername:filename). You can also play MIDI and wav files with the MOVIE command.

NOTE frequency length volume
Plays any of the standard MIDI notes. <frequency> is the pitch and must be a number from 1 to 127. <length> must be a number indicating how long the note will continue playing. The length is 60 per second, not 100 per second as the DELAY command is. <volume> must be from 0 to 127 and indicates the sound volume you want to use. The volume paramter is optional. If you don't set the volume then it will default to 127 (loud).

NOTEALERT your message here
Displays an alert window with a standard Mac note alert icon and an OK button with the message that you place after NOTEALERT. You can put the value of a variable in an alert by using $variable$. See ALERT and CAUTIONALERT for other alert windows.

ON KEYDOWN
  ' do commands here
END KEYDOWN
This is a block KEYDOWN structure. The commands on the lines between ON KEYDOWN and END KEYDOWN are executed when a key on the keyboard is pressed. When a key is pressed, the built in variable named KeyDown$ is set to a string containing that key. You can then check if a certain key was pressed by checking the KeyDown$ variable. For example, if the player presses A then KeyDown$ will be set to "A". See the built in variables at the bottom of this reference for more information on the KeyDown$ variable.
Example:
ON KEYDOWN
  IF keyDown$ = "A" THEN ALERT "You pressed A."
END KEYDOWN

ON MOUSEDOWN doAnyCommand
Executes any single line command when the mouse is pressed down. ON MOUSEDOWN is local to the current card. Once you branch to another card, it's no longer in effect.

ON MOUSEDOWN
  ' do commands here
END MOUSEDOWN
This is a block MOUSEDOWN structure. The commands on the lines between ON MOUSEDOWN and END MOUSEDOWN are executed when the mouse is pressed down. A block ON MOUSEDOWN structure is global. It will still be in effect if you branch to another card. Use MOUSE OFF to turn it off.

ON MOUSEUP doAnyCommand
Executes any single line command after the mouse is clicked. ON MOUSEUP is local to the current card. Once you branch to another card, it's no longer in effect.

ON MOUSEUP
  ' do commands here
END MOUSEUP
This is a block MOUSEUP structure. The commands on the lines between ON MOUSEUP and END MOUSEUP are executed when the mouse button is released after being pressed down. A block ON MOUSEUP structure is global. It will still be in effect if you branch to another card. Use MOUSE OFF to turn it off.

ON TIMER time doAnyCommand
Executes any single line command after <time> amount of time has elapsed (100 = 1 second). If <time> is a positive number, the timer will only work while on the card the command was executed from. Once the game branches to another card, the timer is turned off. If <time> is a negative number, it will be active across cards (global) until either the <time> amount of time elapses and the line is executed or you set the timer to off. See the TIMER OFF command.

ON TIMER time
  ' do commands here
END TIMER
This is a block TIMER structure. The commands on the lines between ON TIMER and END TIMER are executed after <time> amount of time has elapsed (100 = 1 second). If <time> is a positive number, the timer will only work while on the card the command was executed from. Once the game branches to another card, the timer is turned off. If <time> is a negative number, it will be active across cards (global) until you set the timer to off. See the TIMER OFF command.

PICT cardnumber
Puts the picture from card <cardnumber> into the current card's picture area.

POPFIELD text to put in field
Draws a rectanglar box across the bottom of the picture with the text you want to display inside the box. The box automatically disappears when themouse is clicked.

PRINT text to put into text area
The PRINT command allows you to put text into the text area of cards. You can put the value of a variable in the text by using $variable$. If you put a semicolon at the end of the text then the next PRINT command will print text continuing where the previous text ended rather then beginning on the next line.
Example:
PRINT You have $gold$ gold.

variable = RANDOM rand1 rand2 rand3 rand4 rand5
Lets you choose a random number. You can have from 1 to 10 parameters. If there is only one parameter after RANDOM and it's a positive number, then a random number from 1 to <rand1> will be chosen. If it's a negative number, then a number from 0 to <rand1> will be chosen. If there are 2 to 10 paramters, then a random one of those will be selected.
Examples:
Pick a random number from 1 to 25 and put it in X:
  X = RANDOM 25
Randomly pick either 10, 15, or 18 and put it in X:
  X = RANDOM 10 15 18

REFRESH PICT | TEXT
Puts the card's default picture and text onto the card. REFRESH used with no parameter will refresh both the picture and text. REFRESH PICT refreshes the picture only. REFRESH TEXT refreshes the TEXT only.

REM
This is used for remarks that you want to put in your code possible to remind yourself what a certain piece of code is for. Any line starting with REM will be ignored. You can also use the ' apostrophy character rather than REM. This must be at the beginning of a line of code. Remarks cannot be put in the middle of a line.

REPEAT howManyTimes
  ' do commands here
END REPEAT
This will continue looping through any commands between REPEAT and END REPEAT until the loop has been executed <howManyTimes> times.  If you leave out the <howManyTimes> parameter, it will loop until an EXIT REPEAT is executed. When test running your program from within GameMaker, you can break out of a repeat loop by pressing the OPTION key.
Example:
' this loops through card pictures 100 and 101 three times
REPEAT 3
  PICT 100
  DELAY 10
  PICT 101
  DELAY 10
END REPEAT

RESET
Resets all variables to 0. It's usually a good idea to put this as the first line of the Card Script in card #1 so that anytime a player starts a new game, all variables will be reset. If you need some variables to start with a value other than 0, set them after using RESET.

var1$ = RIGHT$ var2$ x
Sets var1$ to the right x amount of characters in var2$. See also: LEFT$, MID$, and WORD$.

SELECT CASE var
  CASE var1
    ' do this if var1 = var
  CASE var2
    ' do this if var2 = var
  CASE ELSE
    ' do this if no CASE is true
END SELECT
Use a SELECT structure to conditionally execute a block of code based on a test variable. The test variable can be either a numerical variable or a string variable. See also: IF...THEN.

SETAREA clickareanumber x1 y1 x2 y2
Places and the click area <clickareanumber> on the current card at the specified coordinates of <x1> <y1> (top, left corner point of click area). If you omit the last 2 paramters, the click area will be moved but remain the same size. Using the last 2 paramters allows you to move and resize the click area. See also: MOVEAREA.

SETCURSOR cursorNumber
Sets the cursor to the specified cursor. Using a negative number will hide the cursor. Use the following values for <cursorNumber>:
-1 = invisible cursor
0 = standard arrow cursor
1 = I beam cursor
2 = cross hair cursor
3 = wide cross hair cursor
4 = watch cursor

SETWINDOWTITLE new title of window
Lets you rename the title of the current card (the window title). You can put the value of a variable in the title by using $variable$. If you use SETWINDOWTITLE alone without a name parameter, the card name will be set to it's original name.

SHOWAREA clickAreaNumber
Displays or turns on the click area numbered <clickAreaNumber>. See HIDEAREA to hide a click area.

SHOWBUTTON buttonid buttonname
Shows button number <buttonid>. The <buttonName> parameter is optional and lets you temporarily rename the button. The button will revert back to it's original name whenever the card is reopened. Using SHOWBUTTON with no parameters shows all named buttons on the card. See the HIDEBUTTON command for hiding a button.

SHOWCOUNTER countername
Shows the counter if it was hidden or if you want to change the name of the counter. The countername parameter isn't needed if you only want to show the counter without changing the name. Use HIDECOUNTER to hide the counter.

SHOWSTATUSBAR statusbarname
Shows the statusbar if it was hidden or if you want to change the name of the bar. The statusbarname parameter isn't needed if you only want to show the bar without changing the name. Use HIDESTATUSBAR to hide the bar.

SOUND soundname
Plays the sound named <soundname>.

SPRITE spriteNumber x y fileName$
Draws the sprite at the specified x, y location. You can have up to 10 sprites in the window at once. After you've drawn a sprite once, you can leave out fileName$ for further sprite drawing with that sprite number to speed up drawing of the sprite. To hide a sprite, use a negative number for <spriteNumber> with no other parameters.

SPRITE SCALE scaleAmount spriteNumber x y fileName$
Draws the sprite at the specified x, y location scaled by scaleAmount. The scaleAmount parameter should be the percentage to scale the sprite. For example, setting scaleAmount to 25 would draw the sprite 25% of it's original size. After you've drawn a sprite once, you can leave out fileName$ for further sprite drawing with that sprite number to speed up drawing of the sprite.

var = SPRITECOLLIDE spriteNumber1 spriteNumber2
Tests if two sprites have collided. <var> returns 1 if they have collided and 0 if they haven't.

STATUSBAR amount cardnumber maxvalue
Adds <amount> to the status bar. A negative number moves the bar to the left and a positive number moves the bar to the right. The <cardnumber> is the card that GameMaker should go to if the bar is at either 0 or at the maximum value for the bar after adding <amount> to it.  The optional <maxvalue> parameter lets you set the maximum value for the status bar. It can be set from 1 to 100.

STOP SOUND | MOVIE
Stops playing either a sound or a QuickTime file that only has a sound track (including MIDI or wav files). It does not work with the NOTE command or QuickTime movies that have movie data.
Examples:
Stop playing a sound:
  STOP SOUND
Stop playing a QuickTime file:
  STOP MOVIE
Stop playing both a sound and a movie:
  STOP SOUND MOVIE

var1$ = STR$ var2
Sets var1$ to a string containing the numerical value of var2.

SWAP variable1 variable2
Exchanges the value of 2 variables. If variable1 = 10 and variable2 = 20, doing a swap will set variable1 to 20 and variable2 to 10.

TIMER OFF
Turns off the TIMER if it was on. See the ON TIMER command for instructions on using the TIMER.

TIMER time
Changes the amount of time between executions of an active TIMER.

TOGGLE variable
Toggles variable between 0 and 1. If variable = anything other than 0 then it's set to 0. If variable = 0 then it's set to 1.

var$ = UCASE$ var$
Sets var$ to all upper-case characters. For example, "Hello" would be changed to "HELLO".

USERASK askQuestionHere
Ask the player a question by displaying a window with the question and a text field for the player to type in an answer. The player's answer is returned in the built in variable named Userask$.
Example:
USERASK What does 2 + 2 equal?
IF Userask$ = "4" THEN ALERT You're right

var1 = VAL var2$
Sets var1 to the numerical value of var2$.
Example: (this makes x = 125)
a$ = "125"
x = VAL a$

WINDOW PICTURE | SPLASH  | TEXT nameOfFile
Opens a window to display either a picture from a graphics file or a text file with a scroll bar. The difference between PICTURE and SPLASH is that using PICTURE will display a window with a title bar and close box while using SPLASH will display a window with no title bar or close box. The user will need to press the mouse button to close a SPLASH window.

WINDOW INVENTORY
Functionally equivalent to INVENTORY WINDOW.

var1$ = WORD$ var2$ x
Sets var1$ to the x word in var2$. See also: LEFT$ and RIGHT$.
Example: (this makes b$ = "Al")
a$ = "My name is Al"
b$ = WORD$ a$ 4


----------
VARIABLES
----------
Variables are created in your code, not in another window ahead of time. If you have a Button code that has:
  key = 1
That will create a variable named key that is equal to 1. All variables are global so you can then test to see if key = 1 in any other Button, Card, or Click Area code. You can make a variable equal to any number from -32767 to 32767 or you can make string variables by placing quotation marks around the text string.
Examples:
If you have a button named "Get key" and a player clicks on the button which executes your code and you have something like this in the button script:
  IF key = 1 THEN ALERT You already have the key.
  key = 1
The above code will show an alert message window if the key was already set to 1. It will then set the key to 1 in case it wasn't = to 1. The idea here is that you are keeping your own inventory list. You can then check to see if the player has the key when they are on another card. Later in the game there can be a button named "Open Door". The code for that button can check to see if the player got the key earlier in the game.
  IF key = 1 THEN GOTOCARD 100
  IF key = 0 THEN ALERT You need a key to unlock the door.

You can also make variables equal to other variables and you can add or subtract from them:
  gold = gold + 10
  experience = gold * 2

The limitations of variables are as follows:
-Number variables must be integers in the range of -32767 and 32767.
-Complex math is not supported and parenthesis are not allowed. For example, X = Y + 5 will work fine, but X = Y + (Z * 5) will not.
-There must be a space between names, numbers, and signs except when used as a single sign such as <> and ><. For example:
  gold=gold+10
will not work because there needs to be spaces between each item. It may not generate an error, so you should be careful when writing these lines. The correct way to write it is:
  gold = gold + 10


--------------------
BUILT-IN VARIABLES
--------------------
Counter
The value of this variable will be displayed in the bottom right of the main window if you have enabled the Counter in the "Game Options" menu. The display will automatically be updated whenever you change its value in any of the scripts.

CurrentCard
Returns the current card number.

Barvalue
Returns the current value of the Status Bar. You can also use it to set the value of the Status Bar. For other ways of using the Status Bar, see the STATUSBAR command.

Date$
Returns the current date as a string variable in the format mm/dd/yy.

Inventory$
Returns the currently selected inventory item, if any.

IsMoviePlaying
Returns 1 if a QuickTime movie is playing. Returns -1 if a midi, wav, or other QT audio format is currently playing. Returns 0 otherwise.

IsSoundPlaying
Returns -1 if a sound used with the SOUND command is playing. Returns 0 otherwise.

KeyDown$
When a key is pressed, keyDown$ is set to a string containing the key that was pressed. For example, if the player presses "A" then keydown$ will be set to "A". The keyDown$ variable will be set to a one letter string containing the key that was pressed except for the arrow keys and the delete key. Arrow keys return UPARROW, DOWNARROW, LEFTARROW, or RIGHTARROW. The delete key returns DELETE.

LoopScript
When a card script is executed and the Loop Script option is turned on for the card script, LoopScript will return 0 for the first run through the script and returns a positive number for all additional loops through the script.

MouseHorz
Returns the horizontal location of the mouse. Works in conjunction with MouseVert.

MouseDown
Returns 1 if the mouse button is currently down or 0 if it's not.

MouseVert
Returns the vertical location of the mouse. Works in conjunction with MouseHorz.

RecentCard
Returns the number of the most recent card that the player was on. It should not be directly changed in scripts.

SpriteClicked
Returns the number of the sprite that was last clicked or 0 if none were clicked. This variable is updated whenever the mouse is clicked.

Time$
Returns the current time as a string variable in the format hh:mm:ss.

TotalCards
Returns the total number of cards that a player has accessed. This includes multiple acceses to the same card, so this number will keep increasing as game play continues. This can be a good way to keep track of time in a game.

Userask$
Returns the most recent answer the player typed into a USERASK dialog window.
